Exchange Maven Facade icon

Exchange Maven Facade

3.0.x
(2 reviews)

Getting Started

Configure Maven

Create a maven client settings file: ~/.m2/settings.xml

Use Anypoint Platform Credentials

Configure your credentials for the Exchange Maven Facade API:

<?xml version="1.0" encoding="UTF-8"?>
<settings xmlns="http://maven.apache.org/SETTINGS/1.0.0"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://maven.apache.org/SETTINGS/1.0.0
http://maven.apache.org/xsd/settings-1.0.0.xsd">
  <servers>
<server>
  <id>Repository</id>
  <username>USERNAME</username>
      <password>PASSWORD</password>
    </server>
  </servers>
</settings>

The <id> value is arbitrary, but must have the same value in your pom.xml and settings.xml files. The <server> ... <id> value in the settings.xml file is the same value as the <repository> ... <id> value in the pom.xml file.

Use an Access Token

Exchange Maven Facade supports using a Core Services access token instead of a username and password.

Obtain a token with this request.

If you sign in with an identity provider (IdP), you have the alternative option to use your IdP token.

In the file settings.xml , specify the special user ~~~Token~~~.

Replace ACCESS_TOKEN with the Core Services access token.

<?xml version="1.0" encoding="UTF-8"?>
<settings xmlns="http://maven.apache.org/SETTINGS/1.0.0"
 xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
 xsi:schemaLocation="http://maven.apache.org/SETTINGS/1.0.0
 http://maven.apache.org/xsd/settings-1.0.0.xsd">
  <servers>
    <server>
      <id>Repository</id>
      <username>~~~Token~~~</username>
      <password>ACCESS_TOKEN</password>
    </server>
  </servers>
</settings>

Use Connected Application Authentication

  • Create a connected application (App acts on its own behalf (client credentials)) and either provide read-only access by setting the scope of Exchange Viewer, or provide read and write access by setting either the scope of Exchange Administrator or the scope of Exchange Contributor.
  • Define the username as ~~~Client~~~ and the password as clientId~?~clientSecret.
  • Include the connected application in the file settings.xml in your repository:
<?xml version="1.0" encoding="UTF-8"?>
<settings xmlns="http://maven.apache.org/SETTINGS/1.0.0"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://maven.apache.org/SETTINGS/1.0.0
http://maven.apache.org/xsd/settings-1.0.0.xsd">
  <servers>
    ...
    <server>
      <id>Repository</id>
      <username>~~~Client~~~</username>
      <password>clientId~?~clientSecret</password>
    </server>
  </servers>
</settings>

Publish with Maven

Successful publication using the Maven Facade API version 3 requires configuring the Maven plugin correctly.

The plugin performs these actions:

  • Before uploading the asset's files, validate that the asset can be created, including checking asset ID availability.
  • Give the publication status.
  • When all files have finished uploading, mark the asset publication complete.

These examples show how to configure your POM file.

For complete examples, see the section Examples.

Use mule-maven-plugin to Publish Mule 4 Assets

The latest version of this plugin is 3.5.0.

This example shows the build section of pom.xml.

This example packages a mule-application asset.

    <build>
        <plugins>
            <plugin>
                <groupId>org.mule.tools.maven</groupId>
                <artifactId>mule-maven-plugin</artifactId>
                <version>3.5.0-SNAPSHOT</version>
                <extensions>true</extensions>
                <configuration>
                    <classifier>mule-application</classifier>
                </configuration>
            </plugin>
        </plugins>
    </build>

Note: mule-maven-plugin is integrated with exchange-mule-maven-plugin.

Use exchange-mule-maven-plugin to Publish Custom Assets

The latest version of this plugin is 0.0.13.

This example shows the build section of pom.xml.

This example publishes a custom asset.

     <build>
        <plugins>
            <plugin>
                <groupId>org.mule.tools.maven</groupId>
                <artifactId>exchange-mule-maven-plugin</artifactId>
                <version>0.0.9</version>
                <executions>
                    <execution>
                        <id>validate</id>
                        <phase>validate</phase>
                        <goals>
                            <goal>exchange-pre-deploy</goal>
                        </goals>
                    </execution>
                    <execution>
                        <id>deploy</id>
                        <phase>deploy</phase>
                        <goals>
                            <goal>exchange-deploy</goal>
                        </goals>
                    </execution>
                </executions>
            </plugin>
        </plugins>
    </build>

Create Asset with Lifecycle State

A new asset version is in the development state or the default stable state.

To create an asset version in the stable state, use Maven normally.

To create an asset version in the development state, use the Anypoint Exchange Maven Facade API version 3 and set the version of the asset to SNAPSHOT. This behavior allows for backward compatibility with legacy APIs.

A SNAPSHOT asset is permanently in the development state and cannot be promoted to any other state.

An asset with the version SNAPSHOT published with the Anypoint Exchange Maven Facade API version 1 or version 2 has the state stable.

Uploading a SNAPSHOT template asset in the development state example:

In a terminal:

  1. Execute: git clone https://github.com/mulesoft-labs/exchange-documentation-samples.git
  2. Execute: cd exchange-documentation-samples/template-snapshot
  3. Edit the file pom.xml and replace the values YOUR_ORG_ID, YOUR_GROUP_ID, and YOUR_ASSET_ID with your asset’s organizationId, groupId, and assetId.
  4. Execute: mvn clean deploy
  5. Open your Exchange home page and view the template in the development state.

If you execute mvn clean deploy multiple times, the asset is overwritten without any errors.

Note: An asset that is in development state and is not a SNAPSHOT version cannot be consumed through Maven.

Troubleshooting

If the build fails during the deploy stage with a status code of 412 (Precondition Failed), then the <goal>exchange-pre-deploy</goal> has not been executed. To fix this error, ensure that goal is set inside the executions section of the plugin.

The error looks similar to this:

[INFO] BUILD FAILURE
[INFO] ------------------------------------------------------------------------
[INFO] Total time:  2.871 s
[INFO] Finished at: 2020-11-09T12:11:54-03:00
[INFO] ------------------------------------------------------------------------
[ERROR] Failed to execute goal org.apache.maven.plugins:maven-deploy-plugin:2.7:deploy (default-deploy) on project hello-world-pom: Failed to deploy artifacts: Could not transfer artifact 1da12ec1-7614-43a3-bf24-ff754cab8ddf:hello-world-pom:pom:1.0.3 from/to repository-id ([https://maven.anypoint.mulesoft.com/api/v3/organizations/orgId/maven/](http://localhost:8088/api/v3/organizations/1da12ec1-7614-43a3-bf24-ff754cab8ddf/maven/)): Transfer failed for [https://maven.anypoint.mulesoft.com](http://localhost:8088/api/v3/organizations/1da12ec1-7614-43a3-bf24-ff754cab8ddf/maven/)[/api/v3/organizations/](http://localhost:8088/api/v3/organizations/1da12ec1-7614-43a3-bf24-ff754cab8ddf/maven/1da12ec1-7614-43a3-bf24-ff754cab8ddf/hello-world-pom/1.0.3/hello-world-pom-1.0.3.pom)[orgId](http://localhost:8088/api/v3/organizations/1da12ec1-7614-43a3-bf24-ff754cab8ddf/maven/)[/maven/groupId/assetId/version/filename](http://localhost:8088/api/v3/organizations/1da12ec1-7614-43a3-bf24-ff754cab8ddf/maven/1da12ec1-7614-43a3-bf24-ff754cab8ddf/hello-world-pom/1.0.3/hello-world-pom-1.0.3.pom) 412 -> [Help 1]

Consume with Maven

To consume an asset published in Exchange using Maven, edit your POM file. In the repositories section, add the Exchange Maven Facade as a repository. In the dependencies section, add the groupId, artifactId (assetId), and version of the asset to use as a dependency.

For example:

<project xmlns="http://maven.apache.org/POM/4.0.0"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="http://maven.apache.org/POM/4.0.0
                      http://maven.apache.org/xsd/maven-4.0.0.xsd">
[...]

  <dependencies>
    <dependency>
      <groupId>org.mule.modules</groupId>
      <artifactId>mule-module-sfdc</artifactId>
      <version>8.0.0-SNAPSHOT</version>
    </dependency>
  </dependencies>

[...]

  <repositories>
    <repository>
      <id>Repository</id>
      <name>Corporate Repository</name>
    <url>https://maven.anypoint.mulesoft.com/api/v3/maven</url>
      <layout>default</layout>
    </repository>
  </repositories>
[...]
</project>

Reviews